<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <style xmlns="" type="text/css">
    /* This style sets a margin around the entire page */
        html, body {
            margin: 10px;
        }

        p {
            font: normal 16px verdana, sans-serif;
            margin: 0;
            padding-bottom:12px;
        }

        h1 {
            font: bold 25px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h2 {
            font: bold 19px verdana, sans-serif;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h3 {
            font: bold 19px verdana, sans-serif !important;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        li {
            font: normal 16px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 18px;
            padding-top: 0;
            padding-bottom: 0;
        }

        .pdparam {
            font: italic 16px verdana, sans-serif;
        }

                .term {
                        font: italic 16px verdana, sans-serif;
                        font-weight: normal;
                }

                .type {
                        font: normal 16px verdana, sans-serif !important;
                }

                .parameter {
                        font-style: italic;
                        }

        a:link, a:visited {
            color: blue;
            text-decoration: none;
            font: normal 16px;
        }

        a:hover {
            background-color: #FFFF99;
            font: normal 16px;
        }

        div.funcsynopsis {
            text-align: left;
            background-color: #e6e6e6;
            font: normal 16px verdana, sans-serif;
                        padding-top: 10px;
                        padding-bottom: 10px;
        }

        div.funcsynopsis table {
            border-collapse: separate;
            font: normal 16px verdana, sans-serif;
        }

        div.funcsynopsis td {
            background-color: #e6e6e6;
            border: 0 solid #000;
            padding: 1px;
            font: normal 16px verdana, sans-serif;
        }

        div.refsect1 {
            font-family: verdana, sans-serif;
            font-size: 16px;
        }

        code.constant {
            font: normal 16px courier new, monospace !important;
        }

                span.errorname {
            font: normal 16px verdana, sans-serif !important;
        }

        code.function {
            font: bold 16px verdana, sans-serif !important;
        }

        b.fsfunc {
            font: bold 16px verdana, sans-serif !important;
        }

        code.varname {
            font: italic 16px verdana, sans-serif;
        }

        code.replaceable {
            font: italic 16px courier new, monospace;
        }

        code.funcdef {
            font: normal 16px verdana, sans-serif !important;
        }

        .citerefentry {
            font: normal 16px verdana, sans-serif !important;
        }

        .parameter {
            font-style: italic;
        }

        code.fsfunc {
            font: normal 16px verdana, sans-serif !important;
        }

        /* PARAMETER: This style controls spacing between the terms in Parameter section */
        dt {
            margin-top: 15px;
        }

        /* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */
        div.refsect1 table {
            width: 100%;
                        margin-top: 10px;
            background-color: #FFF;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
                        font: normal 16px verdana, sans-serif;
        }

        div.refsect1 th {
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: bold 16px verdana, sans-serif;
        }

        div.refsect1 td {
            background-color: #FFF;
            padding: 5px;
            vertical-align: text-top;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: normal 16px verdana, sans-serif;
        }

                  div.refsect1 p{
            font: normal 16px verdana, sans-serif;
            margin-top: 8px;
            margin-bottom: 8px;
            padding-top: 0;
            padding-bottom: 0;
        }


        /* EXAMPLE: These styles apply only to the Example section */
        div.refsect2 {
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 table {
            margin-top: 0;
            background-color: #e6e6e6;
            width: 100%;
            border: 0 solid #000;
            padding: 2px;
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 td {
            background-color: #e6e6e6;
            font: normal 16px courier new, monospace !important;
                        white-space:pre;
        }

        /* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */
        div.refsect3 {
            font: normal 11px verdana, sans-serif;
            margin-top: 50px;
            margin-bottom: 20px;
            padding-top: 0;
            padding-bottom: 0;
        }

</style>
    <title>clSetMemObjectDestructorCallback</title>
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <meta name="keywords" content="clSetMemObjectDestructorCallback" />
  </head>
  <body>
    <div class="refentry">
      <a id="id-1"></a>
      <div class="titlepage"></div>
      <div xmlns="" class="refnamediv">
        <a xmlns="http://www.w3.org/1999/xhtml" id="clSetCommandQueueProperty"></a>
        <h1>clSetMemObjectDestructorCallback</h1>
        <p>
            Registers a user callback function that will be called when the memory object is 
            deleted and its resources freed.
        </p>
      </div>
      <div class="refsynopsisdiv">
        <h2></h2>
        <div class="funcsynopsis">
          <table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
            <tr valign="bottom">
              <td>
                <code xmlns="http://www.w3.org/1999/xhtml" class="funcdef"><a class="link" href="scalarDataTypes.html" target="_top">cl_int</a>
                    <strong class="fsfunc">clSetMemObjectDestructorCallback</strong>
                (</code>
                <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="abstractDataTypes.html" target="_top">cl_mem</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">memobj</var>, </td>
              </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="_top">void</a> (CL_CALLBACK  <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*pfn_notify</var>) (<a xmlns="http://www.w3.org/1999/xhtml" class="link" href="abstractDataTypes.html" target="_top">cl_mem</a> memobj, </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="_top">void</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*user_data</var>), </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="_top">void</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*user_data</var><code>)</code></td>
            </tr>
          </table>
        </div>
      </div>
      <div class="refsect1">
        <a id="parameters"></a>
        <h2>Parameters</h2>
        <div class="variablelist">
          <dl class="variablelist">
            <dt>
              <span class="term">
                <code class="varname">memobj</code>
              </span>
            </dt>
            <dd>
              <p>A valid memory object.</p>
            </dd>
            <dt>
              <span class="term">
                <code class="varname">pfn_notify</code>
              </span>
            </dt>
            <dd>
              <p>
                    The callback function that can be registered by the application. This 
                    callback function may be called asynchronously by the OpenCL implementation. 
                    It is the application's responsibility to ensure that the callback function 
                    is thread-safe. The parameters to this callback function are:
                </p>
              <div class="itemizedlist">
                <ul class="itemizedlist" style="list-style-type: disc; ">
                  <li class="listitem" style="list-style-type: disc"><code class="varname">memobj</code>: the memory object being deleted.
                    </li>
                  <li class="listitem" style="list-style-type: disc"><code class="varname">user_data</code>: a pointer to user supplied data.
                    </li>
                </ul>
              </div>
            </dd>
            <dt>
              <span class="term">
                <code class="varname">user_data</code>
              </span>
            </dt>
            <dd>
              <p>Data which will be passed as the <code class="varname">user_data</code> argument when 
                <code class="varname">pfn_notify</code> is called. <code class="varname">user_data</code> can be NULL.</p>
            </dd>
          </dl>
        </div>
      </div>
      <div class="refsect1">
        <a id="notes"></a>
        <h2>Notes</h2>
        <p>
            Each call to <code class="function">clSetMemObjectDestructorCallback</code> registers the specified user
            callback function on a callback stack associated with <code class="varname">memobj</code>. The registered user 
            callback functions are called in the reverse order in which they were registered. The user callback
            functions are called and then the memory object's resources are freed and the memory object is
            deleted. This provides a mechanism for the application (and libraries) using <code class="varname">memobj</code> 
            to be notified when the memory referenced by <code class="varname">host_ptr</code>, specified when the memory object 
            is created and used as the storage bits for the memory object, can be reused or freed.
        </p>
        <p>
            When the user callback function is called by the implementation, the contents of the
            memory region pointed to by <code class="varname">host_ptr</code> (if the memory object is created with
            CL_MEM_USE_HOST_PTR) are undefined. The callback function is typically used by the application to 
            either free or reuse the memory region pointed to by <code class="varname">host_ptr</code>.
        </p>
        <p>
            The behavior of calling expensive system routines, OpenCL API calls to create contexts or
            command-queues, or blocking OpenCL operations from the following list below, in a callback is
            undefined.
        </p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" style="list-style-type: disc">
              <a class="citerefentry" href="clFinish.html">
                <span class="citerefentry">
                  <span class="refentrytitle">clFinish</span>
                </span>
              </a>
            </li>
            <li class="listitem" style="list-style-type: disc">
              <a class="citerefentry" href="clWaitForEvents.html">
                <span class="citerefentry">
                  <span class="refentrytitle">clWaitForEvents</span>
                </span>
              </a>
            </li>
            <li class="listitem" style="list-style-type: disc">
                blocking calls to <a class="citerefentry" href="clEnqueueReadBuffer.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueReadBuffer</span></span></a>,
                <a class="citerefentry" href="clEnqueueReadBufferRect.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueReadBufferRect</span></span></a>,
                <a class="citerefentry" href="clEnqueueWriteBuffer.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueWriteBuffer</span></span></a>,
                <a class="citerefentry" href="clEnqueueWriteBufferRect.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueWriteBufferRect</span></span></a></li>
            <li class="listitem" style="list-style-type: disc">
                blocking calls to <a class="citerefentry" href="clEnqueueReadImage.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueReadImage</span></span></a> and 
                <a class="citerefentry" href="clEnqueueWriteImage.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueWriteImage</span></span></a></li>
            <li class="listitem" style="list-style-type: disc">
                blocking calls to <a class="citerefentry" href="clEnqueueMapBuffer.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueMapBuffer</span></span></a> and 
                <a class="citerefentry" href="clEnqueueMapImage.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueMapImage</span></span></a></li>
            <li class="listitem" style="list-style-type: disc">
                blocking calls to <a class="citerefentry" href="clBuildProgram.html"><span class="citerefentry"><span class="refentrytitle">clBuildProgram</span></span></a></li>
          </ul>
        </div>
        <p>
            If an application needs to wait for completion of a routine from the above list in a callback,
            please use the non-blocking form of the function, and assign a completion callback to it to do the
            remainder of your work. Note that when a callback (or other code) enqueues commands to a
            command-queue, the commands are not required to begin execution until the queue is flushed.
            In standard usage, blocking enqueue calls serve this role by implicitly flushing the queue. Since
            blocking calls are not permitted in callbacks, those callbacks that enqueue commands on a
            command queue should either call <a class="citerefentry" href="clFlush.html"><span class="citerefentry"><span class="refentrytitle">clFlush</span></span></a> 
            on the queue before returning or arrange for <a class="citerefentry" href="clFlush.html"><span class="citerefentry"><span class="refentrytitle">clFlush</span></span></a> 
            to be called later on another thread.
        </p>
        <p>
            The user callback function may not call OpenCL APIs with the memory object for which the
            callback function is invoked and for such cases the behavior of OpenCL APIs is considered to be
            undefined.
        </p>
      </div>
      <div class="refsect1">
        <a id="errors"></a>
        <h2>Errors</h2>
        <p>Returns <span class="errorname">CL_SUCCESS</span> if the command-queue properties are successfully updated. 
        Otherwise, it returns the following:</p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_MEM_OBJECT</span> if <code class="varname">memobj</code> is not a valid memory object.
            </li>
            <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_VALUE</span> if <code class="varname">pfn_notify</code> is NULL.
            </li>
            <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_OUT_OF_RESOURCES</span> if there is a failure to allocate resources required by the
                OpenCL implementation on the device.
            </li>
            <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_OUT_OF_HOST_MEMORY</span> if there is a failure to allocate resources required by the
                OpenCL implementation on the host.
            </li>
          </ul>
        </div>
      </div>
      <div class="refsect1">
        <a id="specification"></a>
        <h2>Specification</h2>
        <p><img src="pdficon_small1.gif" />
            <a href="http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf#page=98" target="OpenCL Spec">OpenCL Specification</a>
        </p>
      </div>
      <div class="refsect1">
        <a id="seealso"></a>
        <h2>Also see</h2>
        <p>
<a class="citerefentry" href="clCreateCommandQueue.html"><span class="citerefentry"><span class="refentrytitle">clCreateCommandQueue</span></span></a>, 
<a class="citerefentry" href="clGetCommandQueueInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetCommandQueueInfo</span></span></a>, 
<a class="citerefentry" href="clReleaseCommandQueue.html"><span class="citerefentry"><span class="refentrytitle">clReleaseCommandQueue</span></span></a>, 
<a class="citerefentry" href="clRetainCommandQueue.html"><span class="citerefentry"><span class="refentrytitle">clRetainCommandQueue</span></span></a> 
        </p>
      </div>
      <div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4>
            Copyright © 
    Copyright © 2007-2010 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.
</div>
    </div>
  </body>
</html>
